home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tcl / CrtPipelin.man < prev    next >
Encoding:
Text File  |  1992-08-07  |  8.0 KB  |  281 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/CrtPipelin.man,v 1.2 91/12/06 10:34:42 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tcl_CreatePipeline tcl
  189. .VS
  190. .BS
  191. .SH NAME
  192. Tcl_CreatePipeline \- create one or more child processes, with I/O redirection
  193. .SH SYNOPSIS
  194. .nf
  195. \fB#include <tcl.h>\fR
  196. .sp
  197. int
  198. \fBTcl_CreatePipeline\fR(\fIinterp, argc, argv, pidArrayPtr, inPipePtr, outPipePtr, errFilePtr\fR)
  199. .SH ARGUMENTS
  200. .AS Tcl_Interp **pidArrayPtr
  201. .AP Tcl_Interp *interp in
  202. Interpreter to use for error reporting.
  203. .AP int argc in
  204. Number of strings in \fIargv\fR array.
  205. .AP char **argv in
  206. Array of strings describing command(s) and I/O redirection.
  207. .AP int **pidArrayPtr out
  208. The value at \fI*pidArrayPtr\fR is modified to hold a pointer to
  209. an array of process identifiers.  The array is dynamically
  210. allocated and must be freed by the caller.
  211. .AP char *inPipePtr out
  212. If this argument is NULL then standard input for the first command
  213. in the pipeline comes from the current standard input.
  214. If \fIinPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
  215. create a pipe, arrange for it to be used for standard input
  216. to the first command,
  217. and store a file id for writing to that pipe at \fI*inPipePtr\fR.
  218. If the command specified its own input using redirection, then
  219. no pipe is created and -1 is stored at \fI*inPipePtr\fR.
  220. .AP char *outPipePtr out
  221. If this argument is NULL then standard output for the last command
  222. in the pipeline goes to the current standard output.
  223. If \fIoutPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
  224. create a pipe, arrange for it to be used for standard output from
  225. the last command, and store a file id for reading from that
  226. pipe at \fI*outPipePtr\fR.
  227. If the command specified its own output using redirection then
  228. no pipe is created and -1 is stored at \fI*outPipePtr\fR.
  229. .AP char *errFilePtr out
  230. If this argument is NULL then error output for all the commands
  231. in the pipeline will go to the current standard error file.
  232. If \fIerrFilePtr\fR is not NULL, error output from all the commands
  233. in the pipeline will go to a temporary file created by
  234. \fBTcl_CreatePipeline\fR.
  235. A file id to read from that file will be stored at \fI*errFilePtr\fR.
  236. The file will already have been removed, so closing the file
  237. descriptor at \fI*errFilePtr\fR will cause the file to be flushed
  238. completely.
  239. .BE
  240.  
  241. .SH DESCRIPTION
  242. .PP
  243. \fBTcl_CreatePipeline\fR processes the \fIargv\fR array and sets
  244. up one or more child processes in a pipeline configuration.
  245. \fBTcl_CreatePipeline\fR handles pipes specified with ``|'',
  246. input redirection specified with ``<'' or ``<<'', and output
  247. redirection specified with ``>'';  see the documentation for
  248. the \fBexec\fR command for details on these specifications.
  249. The return value from \fBTcl_CreatePipeline\fR is a count of
  250. the number of child processes created;  the process identifiers
  251. for those processes are stored in a \fImalloc\fR-ed array and
  252. a pointer to that array is stored at \fI*pidArrayPtr\fR.
  253. It is the caller's responsibility to free the array when finished
  254. with it.
  255. .PP
  256. If the \fIinPipePtr\fR, \fIoutPipePtr\fR, and \fIerrFilePtr\fR
  257. arguments are NULL then the pipeline's standard input, standard
  258. output, and standard error are taken from the corresponding
  259. streams of the process.  Non-NULL values may be specified for
  260. these arguments to use pipes for standard input and standard
  261. output and a file for standard error.  \fBTcl_CreatePipeline\fR
  262. will create the requested pipes or file and return file identifiers
  263. that may be used to read or write them.  It is the caller's
  264. responsibility to close all of these files when they are no
  265. longer needed.  If \fIargv\fR specifies redirection for standard
  266. input or standard output, then pipes will not be created even
  267. if requested by the \fIinPipePtr\fR and \fIoutPipePtr\fR
  268. arguments.
  269. .PP
  270. If an error occurs in \fBTcl_CreatePipeline\fR (e.g. ``|'' or
  271. ``<'' was the last argument in \fIargv\fR, or it wasn't possible
  272. to fork off a child), then -1 is returned
  273. and \fIinterp->result\fR is set to an error message.
  274.  
  275. .SH "SEE ALSO"
  276. \fBTcl_WaitPids\fR, \fBTcl_DetachPids\fR
  277.  
  278. .SH KEYWORDS
  279. background, child, detach, fork, process, status, wait
  280. .VE
  281.